Notebook: one step at a time, in the decided order (PR 17a) - #244

PR 17a of the notebook UX re-evaluation (owner decision 2026-11-09, docs/restart/designs/ux-proposal-2026-11-09.md on MorphoFeature claude/restart-doc). It shows one step at a time in the decided order. It is pure composition: the cards, answers, draft, save and run logic are unchanged. 17b (folding unchanged rows on reopen, the RGB colour composite, block-confirm tags per header group, one-click axes confirm) is not in this PR.

Summary

• notebook_stepper.py (new, ui, 196 lines) holds the generic Stepper:

  • a clickable strip of chips: done is green with ✓, current is blue, to do is grey, and changed on reopen is orange;
  • Back and Next (Next is never blocked) and one visible page at a time (set_visible, so hidden pages keep every widget);
  • overview(n): one line per step, each with a change button.

• notebook_steps.py (new, ui) adds PreprocessingNotebook.steps(), which builds the 13 steps from the existing cards:

  1. Images found
  2. Axes
  3. Pixel sizes
  4. Conditions
  5. Replicates (pairing, then the replicate and technical-repeat names, then Consistency only when it warns)
  6. Compared against
  7. Image type
  8. Stains
  9. Tag channels
  10. Masks
  11. Check and save (opens with the overview of steps 1-10)
  12. Run
  13. Describe the masks

  The optional statistics page stays separate. The module also has the hooks:

  • the strip refreshes when the run step refreshes;
  • a reopened experiment (a published file) lands on its first step that is not done. In a new session that is the axes;
  • a page that holds a card the saved reopening folded unfolds it.

• notebook_step_states.py (new, ui) gives each step's done flag and one-line summary, read from the cards' existing state. On a reopen whose folders changed, an answer step (4-11) that is no longer done is marked "changed".

• notebook_names.py (new): the names-card row builders moved out of notebook_description.py, which goes from 588 to 467 lines. They also fill condition_rows (step 4) and replicate_rows (step 5). These are the same row widgets as names_grid, so the names card renders as before.

• notebook_channels_type.py: new ImageTypeRows, the image-type page. It uses the same ImageTypeColumn cells, answers and refusals, plus the existing confirm_header for an RGB pre-tick. TagGrid.place_types (default True) leaves out the type column when the stepper is used.

• notebook.steps() in the shipped notebook: one code cell showing welcome(), steps() and results_step().

• Embedders: folder_step() and axis_step() keep their signatures and contents. test_steps_one_and_two_embed_as_morphorelate_does passes, and steps is pinned in test_embedding_api.py.

• Text fixes:

  • the "Then confirm whether the images are fluorescence or RGB" sentence is dropped in a described run only, because embedders still have that card;
  • the broken-image placeholder is hidden until a preview is drawn;
  • "same way?" is said to be above;
  • the reader line and the experiment_design.csv lines are behind a Details fold (refusals and warnings stay visible);
  • "unit" becomes "folder" in the channel cards;
  • the texts name the steps by their new numbers ("The run (step 12) can start", "(Tag channels)", "(Masks, step 10)");
  • the pairing help says the IDs are set "with the names below";
  • step 1 says where the consistency warnings went.

• Run page fix: the box plots and curve legends order the replicates within a condition by replicate ID (rep1 before rep2), not by folder name (RunLabels.order). PR Run page: channel and replicate IDs, no-problems icon, plan card, mask kinds #241 had kept the folder order. Regression test: test_replicates_within_a_condition_are_ordered_by_replicate_id, which fails on main.

Notes for review

• Size: 31 files, +1356/−198, which is just over the 1,500-line guide. About 150 of those lines are the moved names rows and about 330 are tests. I would not split it further.
• Reopen landing: the stepper lands on the first step that is not done. Because the axes are confirmed once per session, an unchanged reopen and a changed reopen both land on Axes. After that, the changed steps show orange. One-click axes confirm is 17b.
• Folding: the existing whole-screen fold of a saved reopening (the green line, Run, Change…) still shows on Check and save. Opening Replicates, Compared against or Masks unfolds it. Per-row folding is 17b.
• Not verified: the widgets were driven headless and rendered with embed_minimal_html in Playwright chromium. They were not checked in a live JupyterLab or Colab. The notebook pins RELEASE_REF v0.4.0, which has no steps(), so the pin must move at release (as with the PR 16 pages).

Tests

• New tests/test_notebook_stepper.py (11 tests):
  • Next and Back, and Next never blocked;
  • strip classes and a chip click;
  • the overview with change;
  • the decided order with one page on screen;
  • the cards in their new places;
  • the image-type page, with no type column in the grid;
  • a round trip through every page with Next, Back and every chip, after which every answer and widget value is unchanged;
  • a saved reopen lands on Axes, and a folded card unfolds;
  • a changed reopen turns tags and save orange;
  • consistency shows after pairing and only when it warns;
  • the axes-page text and the preview placeholder.
• Updated tests: test_notebook_file.py (the steps() cell), test_embedding_api.py (pins steps), the folder wording in test_notebook_channels.py, test_notebook_check_save.py, test_notebook_mask_step.py, and test_run_page_labels.py (the order regression).
• python tools/check.py (.[dev,notebook,zarr], Python 3.13): ruff, format and code rules pass; 4856 passed, 4 skipped. The 4 skips are environment-dependent: a case-sensitive file system ×3 and root ignoring file modes ×1. Main gave 4843 passed, 4 skipped.
• Screenshots: 22 PNGs of the whole flow at 1180 px and deviceScaleFactor 2, made from structured synthetic images (tests/channel_images.py). Each one was looked at.

https://claude.ai/code/session_01G3qp9AxjpGPw9xfWAUJNqc

Generated by Claude Code